Cream of the Crop 12

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 12 / Cream of the Crop 12 (Part II) / Cream of the Crop 12 (Part II).iso / OS2 / DUMP.ZIP / DMP.DOC < prev next >

Wrap

Text File | 1996-04-11 | 19.7 KB | 429 lines

Grope file manipulation utilities Overview 2 A short description of each utility 2 Installation 2 Inquiries 3 DMP 3 CAP 6 EXPORT 7 IMPORT 7 Appendix A - field types 8 Overview This document contains a short description of the interactive file manipulation utilities: CAP, DMP, EXPORT and IMPORT, which allow a user to interactively manipulate data files for which the record structure is known. The utilities are all based on the ability to parse C language struct definitions. The user supplies a C header file containing a struct definition (or definitions), that represent the record layout of the data file that the user wishes to manipulate. The utility uses this to build a symbol table, which contains field data type and field offset information, which is then used to manipulate the data on a field by field basis. A short description of each utility DMP - This program produces a field by field dump of a data file. Fields that are stored in a format that is incomprehensible to humans are automatically converted to a human readable format. I.e. binary numbers are displayed as decimal, EBCDIC characters are displayed as ASCII etc. The utility can produce a simple text dump or it can produce a series of forms, which allow the user the added benefit of being able to edit the data in a file. In this instance the data is converted back to its machine format prior to being written to disk. CAP - This utility allows the user to capture data to a file without writing any code to do so. Typically one may want to quickly generate a data file for use in a specific application. This is useful during the testing and development stages of a programming project, which is being written in C, as it allows the user to use the header files for the project to generate data. EXPORT - This utility allows a user to dump the contents of a data file to a text file in which the data is stored in ASCII delimited format. This is useful for exporting files, which the user may wish to import into a database, which supports importing files in ASCII delimited format. IMPORT - This utility allows the user to import a ASCII delimited text file into a data file. All fields are translated from their ASCII form into the machine equivalent. Limitations The software accompanying this document is for demonstration purposes only. It is a fully functional copy of the package with the following restrictions: No support for the following 'C' data types : long, float/double. No support for the special data types : Bcd, ebcdic and binary. Limited macro preprocessing. Installation The accompanying disk contains a version of the utilities for both OS/2 and DOS. To install the utilities for OS/2 copy the files in the OS2 directory to an appropriate directory on your hard disk and modify the path statement in the config.sys file. To install the utilities for DOS copy the files in the DOS directory to an appropriate directory on your hard disk and modify the path statement in the autoexec.bat file. Inquiries Any queries relating to this software can be sent to John Holton, Internet address: sftfocus@iaccess.za. The postal address of Softfocus cc is P.O. Box 51380, Waterfront, Cape Town, South Africa, 8002. The telephone number is 27-21-237633 and the fax number is 27-21-236633. DMP This use of dmp is probably best illustrated by example. I have created a file called "test.h", which contains the structure definitions of the file "test". The records in "test" are defined by the structure DETAILS, which contains another sub structure called ADDRESS. This is the contents of "test.h". typedef unsigned char BYTE; typedef unsigned long DWORD; typedef struct ADDRESS{ char addlines[4][30]; char phone[10]; char zip[5]; }ADDRESS; typedef struct DETAILS{ char name[20]; char sex; DWORD salary; ADDRESS address; }DETAILS; To get a dump of the file test one would enter the following command string: dmp -htest.h -pDETAILS -dtest Where: -h is the header file in which the record definitions are contained. -p is the primary symbol which defines the record structure of the file, "test". In this instance "DETAILS" defines the record structure. -d is the data file that one wishes to dump, in this case "test". The dmp utility will then produce the listing below. Note that the dump contains a field by field view of each record and is far easier to read than a conventional dump which has no knowledge of the structure of the records being dumped. This becomes even more apparent the more complicated the structure as one would have to manually work out the field offset to determine the contents of a possibly deeply nested field. The dmp utility also translates the field data into it decimal/character equivalent which again makes the data content much easier to read. Note that the dmp utility also supports the use of output redirection symbol, >, which allows the user to direct the output to a data file. Record number 001 ----------------- Field Name Type Hex Value Dec/Char equivalent DETAILS.name ( achr) 66 72 65 64 20 62 6c 6f : fred.blo 67 67 73 00 00 00 00 00 : ggs..... 00 00 00 00 : .... DETAILS.sex ( char) 6d : m DETAILS.salary ( dword) d2040000 : 1234 DETAILS.address.addlines[0] ( achr) 35 20 6d 6f 72 61 79 20 : 5.moray. 70 6c 61 63 65 00 00 00 : place... 00 00 00 00 00 00 00 00 : ........ 00 00 00 00 00 00 : ...... DETAILS.address.addlines[1] ( achr) 6f 72 61 6e 6a 65 7a 69 : oranjezi 63 68 74 00 00 00 00 00 : cht..... 00 00 00 00 00 00 00 00 : ........ 00 00 00 00 00 00 : ...... DETAILS.address.addlines[2] ( achr) 63 61 70 65 20 74 6f 77 : cape.tow 6e 00 00 00 00 00 00 00 : n....... 00 00 00 00 00 00 00 00 : ........ 00 00 00 00 00 00 : ...... DETAILS.address.addlines[3] ( achr) 73 6f 75 74 68 20 61 66 : south.af 72 69 63 61 00 00 00 00 : rica.... 00 00 00 00 00 00 00 00 : ........ 00 00 00 00 00 00 : ...... DETAILS.address.phone ( achr) 34 36 31 34 34 30 36 00 : 4614406. 00 00 : .. DETAILS.address.zip ( achr) 38 30 30 31 00 : 8001. If one wished to edit the data in the file "test", one would enter the following command string: dmp -htest.h -pDETAILS -dtest -e -h specifies the name of the C header file in which the structure definitions are contained. -p specifies the primary struct name that defines the record. -d specifies the name of the data file that is to be dumped or edited. -e specifies that the dmp program must generate forms enabling the user to edit and modify the data in the records. The user will then be presented with a form defining the top most level of the structure being dumped. The first line of the form is broken up as follows: The label on the left is the name of the current structure. The portion to the right gives the record number that is being displayed together with the full name of the structure relative to the overall structure. This will become more apparent as we delve more deeply into the structure. Each subsequent line of the form represents each field in the structure. The name of each field is displayed on the left. This is followed by the type of field. (List of field types can be found in appendix A). Followed by the actual field contents. Note that this system automatically translates data into is character equivalent, making it much easier to understand than the hex data produced by a conventional dump. Once the user modifies a record the data is translated back to its date equivalent based on the field type, before being written to disk. The user may move around in the form using the return key or the down/up arrow keys. One can delete the contents of a field by pressing Alt-d and once the contents of the form have been modified the user can press Alt-G to rewrite the record to disk. Pressing Alt-f will cause the program to exit. Pressing the Page Dn key will cause the program to display the next record without modifying the current one. The top level form for the record defined by DETAIL appears below. Note that each field name if followed by its field type (for a complete description of the field types see Appendix A). This information if followed by a field containing the actual data in translated form. Note that in the case of the address field, the field is represented by a + sign. This signifies that there is a sub structure for which there will be an additional form. If the user presses the Enter key while in this field the form associated with the substructure will be displayed. +------------------------------------------------------------+ | DETAILS [Record:1] DETAILS | | | | | | | | name ( achr) fred bloggs | | sex ( char) m | | salary ( dword) 1234 | | address (struct) + | | | +------------------------------------------------------------+ The address field contains more deeply nested structures. In this instance the addlines field which is a multi-dimensional array of character strings. Pressing the Enter key in this instance will present the user with a field allowing him or her to specify the index of the array element that they wish to edit. Note that this index form automatically increments if one simply presses the enter key without changing the value. I.e. it will automatically step through each successive array element unless told to go to a specific element. +----------------------------------------------------------+ | address(s) [Record:1] DETAILS.address | | | | | | | | addlines ( array) + | | phone ( achr) 4614406 | | zip ( achr) 8001 | | | +----------------------------------------------------------+ +-------------------------------------------------------+ | Element [0-3] | | | | ONE_DIMENSION.rowIndex ( short) 0 | | | +-------------------------------------------------------+ +-----------------------------------------------------------------------+ | addlines[0] [Record:1] DETAILS.address.addlines[0] | | | | | | | | addlines ( achr) 5 moray place | | | +---------------------------------------------------------------------- + In this way one can navigate through the forms that represent the various structures that make up the record. It is not necessary to go to a deeply nested substructure if the user only wishes to modify the higher level portion - pressing the Alt-G key at any point will store the modified record and automatically display the top level structure of the next record. Additional optional parameters. -o Specifies the starting offset from which the dmp program will dump the data. Syntax: -o[number] I.e. -o100 will start dumping the file from offset 100 (decimal). Note that the first byte of the file is at offset 0. If you do not specify the -o parameter the dmp program will start dumping the file from offset 0. -z specifies the structure packing boundary which conforms with the compiler that created the file. Syntax: -Zp[number] This option sets the packing of data in structures and unions to the same boundary. The <number> field represents 1-, 2-, or 4-byte boundaries where each structure member is stored after the first one. If you do not use the -z parameter, structure members are packed on 1-byte boundaries--that is, they are stored contiguously. CAP The capture program allows a user to capture data to a file. If the file does not exist it will be created. If it does exist the data will be appended to the file. The operation of the program is very similar to that of the dmp program and will not be discussed here. The command line parameters that the program accepts are as follows: -h Header file name -p Primary symbol -d Data file For example to capture data to the file "test" one would enter the following command string: cap -htest.h -pDETAILS -dtest EXPORT The export utility will export data from a flat binary file to an ASCII delimited file in which each record is separated by a carriage return/linefeed combination and each field is delimited by a comma - the default delimiter. export -htest.h -pDETAILS -dtest -ftest.exp "fred bloggs",m,1234,"5 moray place","oranjezicht","cape town","south africa","4614406","8001",(cr/lf) "maria bloggs",m,333,"5 morag place","oranjezicht","cape town","south africa","4614406","8001",(cr/lf) Usage -hHeaderFile -dDataFile -pPrimarySymbol -fOutputFileName [- $Delimeter] [-zPacking] [-oOffset]"); Additional Parameters -h Header file -d Data file -p Primary Symbol -f Output file name Optional Parameters -$ Delimiter -z Structure packing -o Starting offset in the data file IMPORT The import utility allows the user to create a data file by importing records that are contained in an ASCII delimited file. Each record is separated by a carriage return/linefeed. For example if one wished to create a file called "newtest" from the data in "test.exp" (See the export example) one would enter the following command line. import -htest.h -pDETAILS -dnewtest -itest.exp Where -h represents the header file in which the structure definitions are contained. -p represents the primary symbol. -d represents the name of the file that one wishes to create. (If the file already exists the data will be appended to it). -i represents the name of the import file in which the delimited data is contained. Optional parameters -$ represents the field delimiting character. (The system defaults to a ','). -z represents the packing boundary. -l represents the name of a log file, which will record any errors in the input process. Note that the import and export utilities are useful if one wishes to modify the record layout of a file. I.e. if one wanted to increase the size of a field in the record one could export the file, then delete the original file, modify the header file and then import the file using the new structure. Appendix A - field types The field types displayed next to the field names in forms and in text are as follows: Displayed 'C' Additional description text equivalent byte unsigned char char char ebcdic EBCDIC dword unsigned long long long ushort unsigned short short short uint unsigned int int int ptr pointer achr array of char abcd array of The utilities support the binary additional keywords of signed coded bcd and unsigned bcd. A struct decimal field specified as signed bcd uses the first byte to specify the sign and the length. An unsigned bcd number has no sign/length byte preceding the number. A 10 digit signed bcd number would be declared as follows: signed bcd number[6]; I.e one byte for the sign/length byte and the 5 bytes for the packed decimal number. bin binary abin array of Due to the memory storage binary system used by Intel processors, an unsigned int would be stored in reverse order. I.e the least significant byte is stored first. A binary number however is stored in its correct sequence. Therefore one would declare a two byte binary number as follows: binary number[2]; aebc array of ebcdic enum enum Enum values are displayed in dumps as their value equivalents. I.e a field declared as having a enum range of {small,medium,large} would display the value 'medium' if the data contained an integer value of 1. bcd binary coded decimal struct struct array array of unknown type float float